M

MLOG

Italiano

Una guida approfondita all'API Temporal di JavaScript, una soluzione moderna per gestire date e orari in modo efficace in diversi contesti internazionali.

API Temporal di JavaScript: Gestione Moderna di Date e Orari per un Pubblico Globale

L'oggetto `Date` di JavaScript è stato a lungo una fonte di frustrazione per gli sviluppatori. La sua mutabilità, l'API incoerente e lo scarso supporto per i fusi orari hanno portato alla creazione di numerose librerie come Moment.js e date-fns per colmare le lacune. Ora, con l'API Temporal, JavaScript offre una soluzione moderna e integrata per gestire date e orari con maggiore chiarezza e precisione. Questo articolo fornisce una panoramica completa dell'API Temporal, concentrandosi sulle sue caratteristiche, vantaggi e utilizzo in diversi contesti internazionali.

Cos'è l'API Temporal?

L'API Temporal è un nuovo oggetto globale in JavaScript progettato per risolvere le carenze dell'oggetto `Date`. Fornisce un'API pulita e immutabile per lavorare con date, orari, fusi orari e sistemi di calendario. Fondamentalmente, mira a rappresentare i concetti di data e ora in un modo che si allinei più strettamente con l'uso e le aspettative del mondo reale, rendendo l'internazionalizzazione molto più semplice.

Caratteristiche Principali:

Oggetti Base di Temporal

L'API Temporal introduce diversi nuovi tipi di oggetti. Ecco alcuni di quelli principali:

Lavorare con le Date

Creare un `Temporal.PlainDate`

Per creare un `Temporal.PlainDate`, puoi usare il costruttore:

const plainDate = new Temporal.PlainDate(2024, 10, 27); // Anno, Mese (1-12), Giorno
console.log(plainDate.toString()); // Output: 2024-10-27

Puoi anche usare il metodo `from`, che accetta una stringa in formato ISO 8601:

const plainDateFromString = Temporal.PlainDate.from('2024-10-27');
console.log(plainDateFromString.toString()); // Output: 2024-10-27

Ottenere i Componenti della Data

Puoi accedere ai singoli componenti della data usando proprietà come `year`, `month` e `day`:

console.log(plainDate.year); // Output: 2024
console.log(plainDate.month); // Output: 10
console.log(plainDate.day); // Output: 27

Aritmetica delle Date

Per aggiungere o sottrarre giorni, settimane, mesi o anni, usa i metodi `plus` e `minus`. Questi metodi restituiscono un nuovo oggetto `Temporal.PlainDate`:

const nextWeek = plainDate.plus({ days: 7 });
console.log(nextWeek.toString()); // Output: 2024-11-03

const lastMonth = plainDate.minus({ months: 1 });
console.log(lastMonth.toString()); // Output: 2024-09-27

Confrontare le Date

Puoi confrontare le date usando il metodo `compare`:

const date1 = new Temporal.PlainDate(2024, 10, 27);
const date2 = new Temporal.PlainDate(2024, 11, 15);

console.log(Temporal.PlainDate.compare(date1, date2)); // Output: -1 (date1 è precedente a date2)

Lavorare con gli Orari

Creare un `Temporal.PlainTime`

Per creare un `Temporal.PlainTime`, usa il costruttore:

const plainTime = new Temporal.PlainTime(10, 30, 0); // Ora, Minuto, Secondo
console.log(plainTime.toString()); // Output: 10:30:00

Oppure usa il metodo `from` con una stringa di orario ISO 8601:

const plainTimeFromString = Temporal.PlainTime.from('10:30:00');
console.log(plainTimeFromString.toString()); // Output: 10:30:00

Ottenere i Componenti dell'Orario

console.log(plainTime.hour); // Output: 10
console.log(plainTime.minute); // Output: 30
console.log(plainTime.second); // Output: 0

Aritmetica degli Orari

const later = plainTime.plus({ minutes: 15 });
console.log(later.toString()); // Output: 10:45:00

Lavorare con Data e Ora Insieme

Creare un `Temporal.PlainDateTime`

Puoi creare un `Temporal.PlainDateTime` direttamente o combinando un `Temporal.PlainDate` e un `Temporal.PlainTime`:

const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
console.log(plainDateTime.toString()); // Output: 2024-10-27T10:30:00

const date = new Temporal.PlainDate(2024, 10, 27);
const time = new Temporal.PlainTime(10, 30, 0);
const combinedDateTime = date.toPlainDateTime(time);
console.log(combinedDateTime.toString()); // Output: 2024-10-27T10:30:00

Fusi Orari

Gestire correttamente i fusi orari è cruciale per le applicazioni che trattano con utenti in luoghi diversi. L'API Temporal fornisce un robusto supporto ai fusi orari attraverso gli oggetti `Temporal.ZonedDateTime` e `Temporal.TimeZone`.

Creare un `Temporal.ZonedDateTime`

Per creare un `Temporal.ZonedDateTime`, hai bisogno di un `Temporal.PlainDateTime` e di un identificatore di fuso orario. Gli identificatori di fuso orario si basano sul database dei fusi orari IANA (es. `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`).

const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);
console.log(zonedDateTime.toString()); // Output: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (L'offset dipenderà dalle regole dell'ora legale)

In alternativa, crea un `Temporal.ZonedDateTime` da un `Instant`.

const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Timestamp di esempio
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Fuso orario come 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());

Convertire tra Fusi Orari

Puoi convertire un `Temporal.ZonedDateTime` in un fuso orario diverso usando il metodo `withTimeZone`:

const newTimeZone = 'Europe/London';
const zonedDateTimeInLondon = zonedDateTime.withTimeZone(newTimeZone);
console.log(zonedDateTimeInLondon.toString()); // Output: 2024-10-27T18:30:00+01:00[Europe/London]

Lavorare con gli Offset dei Fusi Orari

Il metodo `getOffsetStringFor` dell'oggetto `Temporal.TimeZone` fornisce la stringa di offset per un dato `Temporal.Instant`:

const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Output: -07:00 (A seconda delle regole dell'ora legale)

È essenziale utilizzare gli identificatori di fuso orario IANA corretti per calcoli accurati. Questi identificatori sono mantenuti e aggiornati regolarmente per riflettere i cambiamenti nell'ora legale e nei confini dei fusi orari.

Durate

L'oggetto `Temporal.Duration` rappresenta un intervallo di tempo. Può essere usato per aggiungere o sottrarre da date e orari.

Creare un `Temporal.Duration`

Puoi creare un `Temporal.Duration` usando il costruttore, specificando anni, mesi, giorni, ore, minuti, secondi, millisecondi, microsecondi e nanosecondi:

const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Anni, Mesi, Giorni, Ore, Minuti, Secondi, Millisecondi, Microsecondi, Nanosecondi
console.log(duration.toString()); // Output: P1Y2M3DT4H5M6.007008009S

Oppure usando una stringa di durata ISO 8601:

const durationFromString = Temporal.Duration.from('P1Y2M3DT4H5M6S');
console.log(durationFromString.toString()); // Output: P1Y2M3DT4H5M6S

Aggiungere Durate a Date e Orari

const plainDate = new Temporal.PlainDate(2024, 10, 27);
const duration = new Temporal.Duration(0, 0, 7); // 7 giorni
const newDate = plainDate.plus(duration);
console.log(newDate.toString()); // Output: 2024-11-03

Nota che l'aggiunta di durate che coinvolgono mesi o anni alle date richiede un'attenta considerazione, poiché il numero di giorni in un mese o anno può variare.

Sistemi di Calendario

L'API Temporal supporta diversi sistemi di calendario oltre a quello gregoriano. Questo è cruciale per le applicazioni che devono gestire date in vari contesti culturali. Sebbene il supporto sia ancora in evoluzione, fornisce una base per future espansioni.

Utilizzare Calendari Alternativi

Per utilizzare un calendario specifico, puoi specificarlo durante la creazione di oggetti Temporal:

const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // L'output specifico può variare a seconda dell'implementazione e della formattazione. Richiede un polyfill in molti ambienti al momento della stesura di questo articolo.

Importante: Il supporto per i calendari non gregoriani potrebbe richiedere polyfill o un supporto specifico del browser/ambiente. Controlla la documentazione dell'API Temporal e le tabelle di compatibilità dei browser per le informazioni più recenti.

Formattazione di Date e Orari

Mentre l'API Temporal si concentra sulla manipolazione di date e orari, la formattazione è tipicamente gestita dall'oggetto `Intl.DateTimeFormat`, che fa parte dell'API di Internazionalizzazione. Gli oggetti Temporal funzionano perfettamente con `Intl.DateTimeFormat`.

Utilizzare `Intl.DateTimeFormat`

Ecco come formattare un `Temporal.PlainDate` usando `Intl.DateTimeFormat`:

const plainDate = new Temporal.PlainDate(2024, 10, 27);
const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatter.format(plainDate)); // Output: October 27, 2024

const formatterGerman = new Intl.DateTimeFormat('de-DE', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatterGerman.format(plainDate)); // Output: 27. Oktober 2024

Puoi personalizzare le opzioni di formato per soddisfare le tue esigenze. Il primo argomento di `Intl.DateTimeFormat` è la locale, che determina la lingua e le convenzioni regionali utilizzate per la formattazione. L'uso di diverse locali (es. 'en-US', 'de-DE', 'fr-FR', 'ja-JP') produce formati di output diversi.

Formattare `Temporal.ZonedDateTime`

La formattazione di `Temporal.ZonedDateTime` è simile, ma puoi anche includere informazioni sul fuso orario nell'output:

const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);

const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', timeZoneName: 'short' });
console.log(formatter.format(zonedDateTime)); // Output: October 27, 2024, 10:30 AM PDT (L'abbreviazione del fuso orario dipende dalle regole dell'ora legale)

Best Practice per l'Internazionalizzazione

Quando lavori con date e orari in un contesto globale, tieni a mente le seguenti best practice:

Confronto tra l'API Temporal e l'Oggetto Date Tradizionale

Ecco una tabella che evidenzia le principali differenze e i vantaggi dell'API Temporal rispetto all'oggetto `Date` tradizionale:

Caratteristica Oggetto `Date` Tradizionale API Temporal
Mutabilità Mutabile (modifica l'oggetto originale) Immutabile (restituisce nuovi oggetti)
Supporto Fusi Orari Limitato e spesso problematico Robusto e accurato, basato sul database dei fusi orari IANA
API Incoerente e difficile da usare Chiara, coerente e intuitiva
Precisione Millisecondo Nanosecondo
Sistemi di Calendario Limitato al Gregoriano Supporta sistemi di calendario alternativi (con supporto in evoluzione)
Internazionalizzazione Richiede librerie esterne per un'internazionalizzazione robusta Supporto integrato e integrazione perfetta con `Intl.DateTimeFormat`

Supporto dei Browser e Polyfill

Essendo un'API relativamente nuova, il supporto dei browser per l'API Temporal è ancora in evoluzione. Controlla le ultime tabelle di compatibilità dei browser (ad esempio, su MDN Web Docs) per vedere quali browser e ambienti la supportano nativamente. Per i browser più vecchi o gli ambienti senza supporto nativo, puoi usare dei polyfill per fornire la funzionalità dell'API Temporal. Cerca "Temporal API polyfill" sul web per trovare opzioni adatte.

Conclusione

L'API Temporal di JavaScript rappresenta un significativo passo avanti nella gestione di date e orari in JavaScript. La sua immutabilità, l'API chiara, il robusto supporto ai fusi orari e le capacità dei sistemi di calendario la rendono uno strumento potente per gli sviluppatori che creano applicazioni che devono lavorare con date e orari in modo accurato e affidabile in diversi contesti internazionali. Sebbene il supporto dei browser sia ancora in evoluzione, i vantaggi dell'API Temporal la rendono degna di essere imparata e adottata per i nuovi progetti. Abbracciando l'API Temporal e seguendo le best practice di internazionalizzazione, puoi creare applicazioni che offrono un'esperienza di data e ora fluida e accurata per gli utenti di tutto il mondo.

Approfondimenti